---
title: "Pipedream Integration Guide"
edit-this-page-url: https://github.com/airweave-ai/airweave/blob/main/fern/docs/pages/auth-providers/pipedream.mdx
subtitle: "Step-by-step guide to integrate Pipedream as an authentication provider for Airweave"
slug: auth-providers/pipedream
---

<div style={{ textAlign: 'center', margin: '2rem 0' }}>
  <img src="/docs/assets/images/auth-providers/pipedream.jpeg" alt="Pipedream Integration" style={{ maxWidth: '300px', borderRadius: '8px' }} />
</div>

## Overview

Pipedream enables workflow automation with 2,000+ integrated apps. Airweave can leverage your existing Pipedream connections to sync data without requiring users to authenticate again.

This integration involves two separate OAuth clients:

1. **Pipedream OAuth client**: Allows Airweave to access Pipedream's API
2. **Source app OAuth clients**: Custom OAuth clients you create for each source app (Notion, Google Drive, etc.)

<Callout type="warning">
**Important**: Pipedream only exposes credentials for accounts created with your own custom OAuth clients. Default Pipedream OAuth connections use the Proxy API.
</Callout>

## Prerequisites

### For Pipedream API access:
- A Pipedream account with API access
- Pipedream OAuth client credentials (for Airweave to Pipedream authentication)

### For source app access:
- Custom OAuth clients created in each source app (Notion, Google Drive, etc.)
- Source app accounts connected to Pipedream using your custom OAuth clients
- Not accounts connected using Pipedream's default OAuth implementations

## Setup Guide


<Steps>
  <Step title="Set up Pipedream OAuth client" toc={true}>
    First, configure the OAuth client that allows Airweave to access Pipedream's API:

1. Log in to [Pipedream](https://pipedream.com)
2. Navigate to your Project Settings
3. Create a new OAuth client for Airweave integration
4. Configure redirect URIs if required
5. Save your `client_id` and `client_secret`

     <video
      src="./create_pipedream_api_key.mp4"
      controls
      loop
      autoplay
      muted
      playsinline
      style={{ aspectRatio: '16 / 9', width: '100%' }}
    >
      Your browser does not support the video tag.
    </video>

<Callout type="info">
**Purpose**: This OAuth client enables Airweave to authenticate with Pipedream's API to retrieve your connected account credentials.
</Callout>

  </Step>
  <Step title="Connect Pipedream to Airweave" toc={true}>
    1. Go to [Airweave Auth Providers](https://app.airweave.ai/auth-providers)
2. Click "Connect" next to Pipedream
3. Enter your Pipedream OAuth client credentials:
   - `client_id` (from step 1)
   - `client_secret` (from step 1)
4. Provide a readable name for this connection
5. Click "Save"
  </Step>

  <Step title="Create custom OAuth clients for source apps" toc={true}>
    For each source app you want to sync (Notion, Google Drive, etc.), you must create custom OAuth clients:



<AccordionGroup>

  <Accordion title="For Notion">
1. Go to [Notion Developers](https://developers.notion.com)
2. Create a new integration
3. Configure OAuth settings with your redirect URIs
4. Save the `client_id` and `client_secret`
  </Accordion>

  <Accordion title="For Other Apps:">
Follow similar steps for Google Drive, GitHub, or other source integrations.
  </Accordion>

</AccordionGroup>

<Callout type="warning">
**Important**: You must use these custom OAuth clients when connecting accounts in Pipedream. Do not use Pipedream's built-in OAuth options.
</Callout>
  </Step>


    <Step title="Connect source apps in Pipedream using custom OAuth" toc={true}>
    1. In Pipedream, go to your project's connections
2. For each source app (Notion, Google Drive, etc.):
   - Choose "Custom OAuth" option
   - Enter your custom OAuth client credentials from Step 3
   - Complete the OAuth flow to connect your account
3. Note the `account_id` for each connection (format: `apn_xxxxx`)
  </Step>
  <Step title="Find your connection details" toc={true}>
    To create source connections, you'll need these identifiers:

1. `project_id`: Found in the URL when viewing your project (e.g., `proj_JPsD74a`)
2. `account_id`: Retrieved via Pipedream UI or API
3. `external_user_id`: Retrieved via Pipedream UI or API

```bash
curl -X GET "https://api.pipedream.com/v1/connect/{project_id}/accounts?include_credentials=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

The response will include account IDs like `apn_gyha5Ky`.
  </Step>

  <Step title="Create Source Connections" toc={true}>
    Create source connections that automatically retrieve credentials from Pipedream:

<CodeBlocks>
```python title="Python"
from airweave import AirweaveSDK

client = AirweaveSDK(api_key="YOUR_API_KEY")

# Create a Notion connection using Pipedream credentials
source_connection = client.source_connections.create(
    name="Company Notion Workspace",
    short_name="notion",
    authentication={
        "provider_readable_id": "my-pipedream-connection-xyz789",  # Your Pipedream connection ID
        "provider_config": {
            "project_id": "proj_JPsD74a",      # From Pipedream
            "account_id": "apn_gyha5Ky",       # From Pipedream API
            "external_user_id": "user123",     # Required: unique user identifier
            "environment": "production",        # Optional, defaults to "production"
        }
    }
)

print(f"Created: {source_connection.name}")
```

```typescript title="TypeScript"
import { AirweaveSDKClient } from "@airweave/sdk";

const client = new AirweaveSDKClient({
  apiKey: "YOUR_API_KEY"
});

// Create a Notion connection using Pipedream credentials
const sourceConnection = await client.sourceConnections.create({
  name: "Company Notion Workspace",
  shortName: "notion",
  authentication: {
    providerReadableId: "my-pipedream-connection-xyz789",  // Your Pipedream connection ID
    providerConfig: {
      project_id: "proj_JPsD74a",      // From Pipedream
      account_id: "apn_gyha5Ky",       // From Pipedream API
      external_user_id: "user123",     // Required: unique user identifier
      environment: "production",      // Optional, defaults to "production"
    }
  }
});

console.log(`Created: ${sourceConnection.name}`);
```

```bash title="cURL"
curl -X POST 'https://app.airweave.ai/source-connections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Company Notion Workspace",
  "short_name": "notion",
  "authentication": {
    "provider_readable_id": "my-pipedream-connection-xyz789",
    "provider_config": {
      "project_id": "proj_JPsD74a",
      "account_id": "apn_gyha5Ky",
      "environment": "production",
      "external_user_id": "user123"
    }
  }
}'
```

<Callout type="warning">
**Note**: API Validation

The API now performs validation on auth provider source connections:

1. **Provider Existence**: 404 error if the specified `provider_readable_id` doesn't exist
2. **Source Compatibility**: 400 error if the provider doesn't support the specified source

**Example error response when provider doesn't support a source:**
```json
{
  "detail": "Source 'github' does not support 'pipedream' as an auth provider. Supported providers: []"
}
```
</Callout>
</CodeBlocks>
</Step>
</Steps>


## How It Works

The integration uses two distinct OAuth flows:

### OAuth flow overview

1. **Airweave to Pipedream**: Uses your Pipedream OAuth client for API access
2. **Pipedream to source apps**: Uses your custom OAuth clients for each source app

```mermaid
sequenceDiagram
    participant You
    participant Airweave
    participant Pipedream
    participant Notion

    Note over You,Notion: Setup Phase (Two OAuth clients)
    You->>Notion: Create custom OAuth client
    Note over You,Notion: client_id: "notion_abc123"<br/>client_secret: "notion_secret"
    You->>Pipedream: Connect Notion with your OAuth client
    Note over You,Pipedream: Uses notion_abc123, not Pipedream's default
    Pipedream-->>You: project_id: "proj_JPsD74a"<br/>account_id: "apn_gyha5Ky"

    Note over You,Notion: Configure Airweave
    You->>Airweave: Configure Pipedream auth provider
    Note over You,Airweave: Uses your Pipedream OAuth client
    You->>Airweave: POST /source-connections
    Note over You,Airweave: provider_readable_id: "pipedream-prod-xyz789"<br/>project_id: "proj_JPsD74a"<br/>account_id: "apn_gyha5Ky"

    Note over You,Notion: Sync data (Runtime)
    You->>Airweave: Trigger sync
    Airweave->>Pipedream: POST /oauth/token
    Note over Airweave,Pipedream: Uses your Pipedream OAuth client
    Pipedream-->>Airweave: Access token (1hr expiry)
    Airweave->>Pipedream: GET /connect/proj_JPsD74a/accounts/apn_gyha5Ky
    Note over Airweave,Pipedream: include_credentials=true
    Pipedream-->>Airweave: Notion OAuth credentials
    Note over Pipedream,Airweave: Returns your custom OAuth tokens
    Airweave->>Notion: Sync with credentials
    Notion-->>Airweave: Pages & databases
    Airweave-->>You: ✓ Sync complete
```

## Field Mappings

Pipedream uses different field names for some credentials:

| Airweave Field | Pipedream Field |
|----------------|-----------------|
| `access_token` | `oauth_access_token` |
| `refresh_token` | `oauth_refresh_token` |
| `client_id` | `oauth_client_id` |
| `client_secret` | `oauth_client_secret` |
| `api_key` | `api_key` |

These mappings are handled automatically.

## Token Management

Pipedream OAuth tokens have specific characteristics:

- **Expiry**: Access tokens expire after 3600 seconds (1 hour)
- **Auto-refresh**: Airweave refreshes tokens 5 minutes before expiry
- **Concurrency**: Token refresh is thread-safe with async locks
- **Grant Type**: Uses `client_credentials` flow

## Proxy Authentication

When you connect accounts using Pipedream's default OAuth clients, credentials aren't directly exposed for security reasons. Instead, Airweave automatically routes API requests through [Pipedream's proxy endpoint](https://pipedream.com/docs/connect/api-proxy), where the actual credentials are injected server-side. This happens transparently - sources continue using the same HTTP client interface whether they're accessing credentials directly (custom OAuth) or through the proxy (default OAuth). The system automatically detects which mode to use based on the OAuth client type, ensuring your data syncs work seamlessly regardless of how the account was connected in Pipedream.

## Troubleshooting

### `Credentials not available`
```
Detail: Credentials not available. Pipedream only exposes credentials for
accounts created with custom OAuth clients, not default Pipedream OAuth.
```
**Root cause**: The account was connected using Pipedream's built-in OAuth client instead of your custom OAuth client.

**Solution**:
1. Disconnect the account in Pipedream
2. Reconnect using "Custom OAuth" option with your own OAuth client credentials
3. Ensure you're using the OAuth client you created in the source app (e.g., Notion Developer Portal)

### `Account app mismatch`
```
Detail: Account apn_xxx is not for app 'notion'
```
**Solution**: Verify the `account_id` corresponds to the correct integration type and was created with the right custom OAuth client.

### `Failed to refresh token` (Airweave to Pipedream)
This affects the connection between Airweave and Pipedream's API:
- Check if your Pipedream OAuth client credentials are valid
- Ensure your Pipedream OAuth client is active
- Verify network connectivity to Pipedream API

### `Failed to refresh token` (Source App Authentication)
This affects the source app tokens retrieved from Pipedream:
- Verify your source app OAuth client (e.g., Notion, Google Drive) is still active
- Check if the source app tokens have been revoked
- Ensure the source app OAuth client has required permissions

### `Missing required auth fields`
- The integration may require fields not provided by your custom OAuth implementation
- Check the field mappings table above
- Verify the source app OAuth client has all required scopes
- Ensure your custom OAuth client configuration matches the source app's requirements

## API Reference

### Create source connection

<CodeBlocks>
```python title="Python"
from airweave import AirweaveSDK

client = AirweaveSDK(api_key="YOUR_API_KEY")

source_connection = client.source_connections.create(
    name="Team Notion",
    short_name="notion",
    provider_readable_id="pipedream-connection-id",
    provider_config={
        "project_id": "proj_JPsD74a",
        "account_id": "apn_gyha5Ky",
        "external_user_id": "user123",
        "environment": "production"         # Optional, defaults to "production"
    }
)
```

```typescript title="TypeScript"
import { AirweaveSDKClient } from "@airweave/sdk";

const client = new AirweaveSDKClient({
  apiKey: "YOUR_API_KEY"
});

const sourceConnection = await client.sourceConnections.create({
  name: "Team Notion",
  shortName: "notion",
  providerReadableId: "pipedream-connection-id",
  providerConfig: {
    projectId: "proj_JPsD74a",
    accountId: "apn_gyha5Ky",
    externalUserId: "user123",
    environment: "production"      // Optional, defaults to "production"
  }
});
```

```bash title="cURL"
curl -X POST 'https://app.airweave.ai/source-connections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Team Notion",
  "short_name": "notion",
  "provider_readable_id": "pipedream-connection-id",
  "provider_config": {
    "project_id": "proj_JPsD74a",
    "account_id": "apn_gyha5Ky",
    "external_user_id": "user123",
    "environment": "production"
  }
}'
```
</CodeBlocks>

## Limitations

1. **Dual OAuth setup required**: You need to create and manage two separate OAuth clients:
   - One for Pipedream API access (Airweave to Pipedream)
   - One for each source app (Pipedream to Notion/Asana/etc.)

2. **Custom OAuth clients only**:
   - Source app connections must use your own OAuth clients
   - Pipedream's built-in OAuth implementations are not supported
   - Cannot reuse existing accounts connected via Pipedream's default OAuth

3. **Token management complexity**:
   - Pipedream API tokens expire hourly, requiring automatic refresh
   - Source app tokens managed separately through Pipedream
   - Multiple token refresh flows to maintain

4. **API rate limits**: Subject to both Pipedream's API limits and source app limits

5. **Credential access**: Only available with `include_credentials=true` parameter and proper OAuth client setup

## Next Steps

- [Browse available sources](/sources)
- [Set up your first sync](/quickstart)
- [Learn about workflow automation](/concepts#workflows)
